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1 Overview 
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An ECO state machine is a way of defining all states an object may be in, in addition to this the state machine controls which 
transitions are valid at any given point preventing the object from moving to an illogical state. For example, a PurchaseOrder 
may have the following states: 


State 

Description 

Valid transitions 

Raising 

The order is new and may still be modified. 

• Raised 



• Canceled 

Raised 

The order has been approved and may no longer be modified. 

• Canceled 

Invoiced 

The order has had an invoice raised against it. 

None 

Canceled 

The order has been canceled, no goods will be delivered. 

None 


The above rules would require an ECO state machine looking something like the following diagram: 
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When an instance of the PurchaseOrder class is created ECO will create a state machine for that object, this state machine 
will execute the ECO state machine diagram modeled against the class. When the state machine executes it will start at the 
"Initial state" in the diagram, illustrated as a solid black circle, immediately the state machine will follow the transition into the 
"Raising" state. The PurchaseOrder instance will remain in this state until either its "Approve" or "Cancel" methods are 
executed, at which point it will move to the appropriate state. The "Invoiced" and "Cancelled" states have no outgoing 
transitions, so once the object enters one of these states there is no possibility for the state to change again. 
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2 Prerequisites and goais 


Prerequisites 

To successfully follow this document the user should have read the preceding articles in this series and have a copy of the 
model created. An understanding of UML state diagrams would be an advantage. 

Goais 

By the end of this document you will be able to 

• Create ECO state machines. 

• Add transitions between various states. 

• Add OCL "guard" expressions to states to prevent transitions. 

• Create embedded state machines (regions). 
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3 Adding a state machine to the Article 
class 


First an ECO state machine will be added to the Article class. At first this state machine will merely determine whether or not 
to automatically publish the article based on the trust level of its author, later it will be extended to include a review process. 

1 . Right-click the Article class and select "Add StateMachine". 



Article 

&:dv: Tect 




Add Method 

+ 

-1— ■ 

CJ 


□e^iriptiDn: String 
ID: AjtDinc 

Add Attribute 

Ctrl + A 


ReasDr Rejected: S 
Slate: String 
,‘Sun^Tiary: String 
Title: String 

Add StateMachine... 






2. Doubleclick the first state and name it "Authoring" 

3. Drag two additional states from the toolbox onto the design surface and name them "Reviewing" and "Published" 
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4. Select the Transition tool from the toolbar at the top of the diagram: 
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5. Drag transitions from Authoring to Revewing, from Reviewing to Published and from Authoring to Published. 

6. You should now have recreated the following ECO state machine diagram. 
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7. Select one of the two outgoing transitions from the "Authoring" state. 

8. In the Properties windows, Set the property "Trigger" to "Publish". 



16. In the same way set the Trigger property for the other outgoing transition to "Publish" (this time, you can select the value 
using the dropdown combobox). 

17. Set the trigger for the transition from Reviewing to Published to the value "ReviewComplete" 

You should now have a diagram that looks something like this, note how the Trigger names are displayed for both outgoing 
transitions of the "Authoring" state: 




Author! ng 
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A running instance of an ECO state machine may have its state changed by invoking a trigger, triggers are generated as 
methods on the class to which the state machine diagram belongs. As you can see from the previous diagram it is possible 
to have more than one transition out of a single state, when modeling multiple transitions out of a single state you must make 
it absolutely clear which route ECO should take by ensuring only one of the transitions is valid. 


• One way of implementing multiple transitions out of a state is to provide each of the transitions with a different trigger. 

This will make it obvious which transition to take as there will be only one that is linked to the trigger method that was 
executed. 

• Another way of specifying a specific path is to add a "Guard" expression to each transition. When two outgoing transitions 
need to share the same trigger (as in the previous diagram - "Publish"), or the transitions have no triggers at all, an OCL 
expression that evaluates to true or false should be assigned to the each of the transitions' "Guard" property where only 
one must evaluate to true. 

A guard will now be added to each of the "Authoring" state's outgoing transitions to ensure that only one of them is valid. 


17. Go back to the class diagram and add a boolean attribute to the Author class called "AutoPublishArticles" 

18. Select the bottom transition (the one leading to the "Published" state). 

19. Enter the following expression into the Guard property (Note that "self" is case sensitive and lowercase) 


self . Author . AutoPublishArticles 


4 





3 


Creating an ECO state machine 


1 9. Now add the following guard to the transition that leads to the "Reviewing" state. 


not self . Author . AutoPublishArt ides 


When the Article. Publish method is executed ECO will find a collection of transitions out of the current state that uses the 
"Publish" trigger. Next ECO will evaluate the Guard expression on each transition and ensure that only one evaluates to 
"true". If no guard expression evaluates to true, or more than one guard expression evaluates to true then an exception will 
be thrown, otherwise the relevant transition will be taken. 


In this example an article will enter the state "Published" if the author has AutoPublishArticles = true, or enter the 
"Reviewing" state if the author has AutoPublishArticles = false. However, in this example there is no trigger on the transition 
out of the "Reviewing" state so ECO will immediately follow the transition out of "Reviewing" and into "Published". To avoid 
this add a new trigger named "ReviewComplete" to the Article class, and then set this as the trigger for the transition from 
"Reviewing" to "Published". 


Your diagram should now look something like this: 
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To test the state machine follow these steps (previously outlined in article #03 - Prototyping): 


1 . Open the prototype form by pressing the prototype button in the modir toolbar 



2. Double-click the Author class in the list on the left of the form. 
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3. Click the "Add" button at the bottom of the object grid in order to add a new author. 

4. Tick the "AutoPublishArticles" check box for the new Author. 

5. Invoke the Author auto-form by double-clicking the first blank column on the data grid to the left of the new Author row. 
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6. Select the [Articles] tab on the Author auto-form. 

7. Click the "Add" button at the bottom of the Articles grid to add a new Article belonging to this author. 
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8. Invoke the Article auto-form, again by double-clicking the first blank column on the grid next to the appropriate row. 

9. Select the [State] tab on the Article auto-form. 

10. Click the "Publish" button and note how the state alters from "Authoring" to "Published". 
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1 1 . Now untick the AutoPublishArticles check box for the author. 

12. Add another new article. 

13. Invoke the Article auto-form for the new article. 

14. Select the [State] tab. 

15. Click the "Publish" button and note how the state alters from "Authoring" to "Reviewing". Note also how the Publish 
button is replaced by a "ReviewComplete" button. 

16. Click the "ReviewComplete" button and the state will change to "Published". 
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Transition guards 

A transition guard is an OCL expression that evaluates to either True or False. When a transition is about to take place ECO 
will inspect each of the transitions out of the current state and compile a list of valid ones. A transition is determined to be 
valid if: 
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1 . The transition is identified as being triggered by the trigger that has been executed, or the transition has no trigger. 

2. The transition has no guard expression, or the guard expression evaluates to true. 

If no transitions are valid or multiple transitions are valid then an exception will be thrown and no transition will take place. 
There are a few rules to take into account when creating transitions with no trigger, or transitions with guard expressions. 


1 . If any of the outgoing transitions have no trigger specified then no transition out of the same state may define a trigger. 

2. If any of the outgoing transitions have a trigger then all other transitions out of the same state must also define a trigger. 

3. If multiple transitions specify the same trigger then only a single transition must be valid. An OCL guard expression must 
be defined on each outgoing transition that uses the same trigger, only one of which should evaluate to True. In the case 
where no triggers are defined all outgoing transitions must have an OCL guard expression. 
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4 Adding regions 


The previous example demonstrated an over simplistic review process. The process consisted merely of indicating that the 
review was complete by invoking the ReviewComplete trigger; this trigger was only added to prevent the state machine from 
automatically taking the transition to "Published", which is the default behavior for a state with no trigger. 


The following steps will demonstrate how to replace the review process by embedding states within the "Reviewing" state in 
order to define a kind of embedded state machine. This definition will reflect a more realistic approach to approving an article 
submitted by an author without the appropriate trust levels by defining the exact steps to take in order to approve or reject 
the submitted article. 


1 . Go to the state diagram, double-click on the transition from "Reviewing" to "Published" and ensure that the Trigger 
property is empty. 

2. Delete the "ReviewComplete" trigger method on the Article class. 

3. Go back to the state diagram. Right-click on the Reviewing-state and choose Add->Region. 

4. The state region is currently called "region 1", click the empty area inside the state and set the name of the new region 
using the Properties window to "ReviewingRegion". The state diagram should look something like this: 



5. Add a "Start State", an "End State" and two normal states. Rename the normal states "Checkingspelling" and 
"CheckingGrammar". 

6. Add a transitions from the start state to "Checkingspelling", from "Checkingspelling" to "CheckingGrammar" and finally 
from "CheckingGrammar" to the end state. 

7. Add triggers to the transitions as in the following illustration. Remember that entering a non existent trigger name on a 
transition will allow you to create the trigger method. 
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8. Now add a new state and a transition from the "Reviewing" state. 

9. Name the new state "Rejected" state and set the transition's trigger to "Reject". 
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Executing the quick prototype tool will enable you to test your modified state machine. 
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5 Entry, Exit, and Effect 


There are points within an ECO state machine execution that let you trigger methods on your class. These are 


Point 

Description 

State. Entry 

Instructions will be processed when a state is entered. 

State. Exit 

Instructions will be processed when a state is left. 

Transition. Effect 

Instructions will be processed when a transition is taken. 


These points will now be utilized in order to provide the Author with feedback as to why their article was rejected. 

1 . Right-click the Article class and add a new attribute "ReasonRejected", set the Type to "string" and the length to 64. 

2. Switch view to the state machine diagram. 

Next a rejected reason will be automatically assigned depending on which stage of the reviewing process the article was 
rejected. 

3. Now change the state diagram so that instead of having a single transition from Reviewing to Rejected you instead have 
two transitions. One from the embedded "Reviewing. Checkingspelling" state to Rejected and one from the 
"Reviewing. CheckingGrammar" state to Rejected. Set both of their triggers to Reject. 
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4. Select the transition from "Checkingspelling" to "Rejected". 

5. In the property window enter the following expression for the "Effect" property 

self . ReasonRejected := 'Spelling' 

Note: There is no terminating semi-colon in Eco Action Language (EAL), semicolon is only used to separate statements. 



Effect self. Rea so n Rej ected : = 'Spelling' 
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Reject 
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6. Repeat these steps for the transition from "CheckingGrammar" to "Rejected" but specify the reason 'Grammar' instead of 
'Spelling'. 

Next the Exit action for the Authoring state will be used to clear the rejected reason, and transitions will be added to enable 
the author to resubmit their article. 


7. Select the "Rejected" state. 

8. Set the "Exit"-property to the following OCL expression, this will ensure that whenever the Article is re-edited there will be 
no Reason Rejected text 


self . ReasonRe jected := '' 


00 
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10. Create a new transition out of the "Rejected" state back to the "Authoring" state. 

1 1 . For the trigger of this new transition enter "Edit" to create a new trigger method. 



The new behavior will inform the author as to why their article was rejected, and will also allow them to edit their article and 
later resubmit it for publishing. If the reviewer wants more control over the text in the reason for rejecting the article it is a 
simple task to add a new transition from Reviewing to Rejected with a new trigger named "RejectWith Reason". The 
RejectWith Reason trigger method would have a single parameter "ReasonRejected: String" and the effect of the transition 
would be: 


self . ReasonRe jected := ReasonRejected 


Note: It is possible to embed sub state machines within the already embedded "Checkingspelling" and "CheckingGrammar" 
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states, in fact you can just keep going! It is also possible to have concurrent regions within a state, so the Reviewing state 
could have a ContentReview region (as outlined above) and a FinancialApproval region where someone from the finance 
department decides how much the article is worth or may reject the article for being too expensive. Both of these regions 
would execute concurrently, so the finance department would be able to work at the same time as the review department. 
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6 Summary 


This article has introduced ECO state machines; consisting of states, transitions, triggers, and regions. ECO state machines 
provide a lot of power to your business layer in a way that is very easy to implement. 
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